home *** CD-ROM | disk | FTP | other *** search
/ Netware Super Library / Netware Super Library.iso / mhs_mail / adminapp / adminapp.doc < prev    next >
Text File  |  1995-01-11  |  20KB  |  554 lines
  1.      ┌───────────────────────────────────────────────────────────┐
  2.      │                                                           │
  3.      │             The Administrator's Apprentice                │
  4.      │                                                           │
  5.      │                                                           │
  6.      │                                                           │
  7.      │      System Management by E-Mail -  An MHS-based NLM      │
  8.      │                                                           │
  9.      └───────────────────────────────────────────────────────────┘
  10.  
  11.  
  12.  
  13.        Contents
  14.  
  15.  
  16.        Introduction
  17.        Requirements
  18.        Installation
  19.        Creating Accounts
  20.        Loading the NLM
  21.        Configuration File
  22.        Commands accepted by E-Mail
  23.        The CRC32 Utility Program
  24.        Planned enhancements
  25.        Revision History
  26.        Ordering Information
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.       Copyright (C) 1994                                   PH Consulting
  44.                                                   A-3704 Grosswetzdorf 1
  45.                                                                  AUSTRIA
  46.  
  47.  
  48.      ┌──────────────┐
  49.      │ Introduction │
  50.      └──────────────┘
  51.  
  52.      Administrator's Apprentice is an NLM for use on NetWare 3.x and 4.x.
  53.      It interfaces with MHS (SMF-70 or SMF-71, i.e. MHS 1.5, Global MHS
  54.      or Infinite Technologies' Connect²) to receive commands from and send
  55.      alerts to the administrator (supervisor).
  56.  
  57.      Functions include:
  58.  
  59.        - NetWare broadcast message to Mail conversion
  60.  
  61.          NetWare broadcast messages to a specified user (the type of
  62.          message normally displayed in the bottom line of a user's 
  63.          screen by the NetWare shell) are not buffered, so they are 
  64.          easy to miss. This NLM traps such messages and sends the 
  65.          administrator an E-mail message instead.
  66.  
  67.          Benign messages may be filtered.
  68.  
  69.        - Remote File Server Console Status
  70.  
  71.          Upon receiving a command to do so, the NLM will take a "snapshot"
  72.          of the server console's virtual screens and return them to the
  73.          administrator.
  74.  
  75.        - Execute console commands
  76.  
  77.          Batches of console commands can be executed. Execution can be
  78.          delayed for a specific time, or until an NLM is loaded/unloaded.
  79.  
  80.        - Print attached files to a specified queue
  81.  
  82.          Automatically print orders, invoices or anything else to a
  83.          printer queue residing on the local file server.
  84.  
  85.        - List directory or calculate file CRC remotely
  86.  
  87.          Want to check which versions of a program a remote site is
  88.          running? Send a one-line E-mail message.
  89.  
  90.        The (multithreaded) NLM runs completely in the background and 
  91.        causes no noticeable server load when idle. It only polls the 
  92.        server in regular intervals.
  93.  
  94.        When executing a command, utmost care is taken to minimize load
  95.        on the server's CPU. The commands execute fast enough to prevent 
  96.        any noticeable server performance degradation.
  97.  
  98.        This NLM is particularly useful for monitoring remote sites that  
  99.        do not have an on-line (WAN) connection to the main LAN, but can
  100.        be reached through E-mail.
  101.  
  102.      ┌──────────────┐
  103.      │ Requirements │
  104.      └──────────────┘
  105.  
  106.        ADMINAPP runs on NetWare 3.11, 3.12, 4.00, 4.01 and 4.02.
  107.  
  108.        Note that ADMINAPP requires CLIB 3.12f or later on NetWare 3.x.  
  109.        If you are running Netware 3.11, don't be alarmed - you can also
  110.        upgrade to CLIB 3.12x. As of this writing, the most current version
  111.        is 3.12g, which is found in the file LIBUP3 or LIBUP4 (available in
  112.        the NOVLIB forum on CompuServe or from ftp.novell.com on Internet).
  113.        Novell does acknowledge a problem with CLIB 3.12g and GMHS 2.0, and
  114.        recommends using CLIB 3.12f in this configuration.
  115.  
  116.        If you are for some reason unable to upgrade to CLIB 3.12f+, please 
  117.        contact PH Consulting (addresses at the end of this document) for
  118.        a separate Backward Compatibility Module.
  119.  
  120.      ┌──────────────┐
  121.      │ Installation │
  122.      └──────────────┘
  123.  
  124.      To install Administrator's Apprentice, copy ADMINAPP.NLM, 
  125.      ADMINAPP.CFG and either ADAPP30D.NLM (for a 30-day trial)
  126.      or ADAPPINS.NLM (for the retail version) to SYS:SYSTEM.
  127.  
  128.      At the file server console, enter
  129.  
  130.        LOAD ADAPP30D
  131.  
  132.      to start the 30 day trial period or
  133.  
  134.        LOAD ADAPPINS
  135.  
  136.      to install the retail product. Note that Administrator's Apprentice
  137.      is licensed by NetWare File Server, independent of NetWare user count
  138.      or MHS licensing.
  139.  
  140.      Next, edit the configuration file. You may use the command 
  141.  
  142.        LOAD EDIT SYS:SYSTEM/ADMINAPP.CFG
  143.  
  144.      at the file server console or any text editor from an attached
  145.      station. Follow the comments in the sample ADMINAPP.CFG to fill in
  146.      the proper parameters for your configuration. You should enter an MHS
  147.      mail address and a local NetWare user name (see description below).
  148.  
  149.      ┌───────────────────┐
  150.      │ Creating Accounts │
  151.      └───────────────────┘
  152.  
  153.      If you have not already done so (or used an existing account), 
  154.      use SYSCON or NETADMIN to create the user account the the NLM 
  155.      will use to log in to the file server. This account need not have 
  156.      any special rights to the file system; it is only used to receive 
  157.      broadcast messages. 
  158.  
  159.      Make sure that this user account is specified in the appropriate
  160.      places in other programs (such as backup utilities) and/or is a
  161.      member of the proper user groups to receive all the broadcast 
  162.      messages that you want. 
  163.  
  164.      Note that you may restrict this account's login address to 
  165.  
  166.        (file server internal net: node 1) 
  167.  
  168.      if you want to make sure it is not used by someone trying to 
  169.      obtain undue access to the server over the network.
  170.  
  171.      Also, if the MHS mail account specified above does not exist yet,
  172.      create it now. IMPORTANT: Make sure that MHS is the preferred 
  173.      application defined for this account.
  174.  
  175.      Verify that you can log in to the server from a workstation
  176.      using the username and password specified in the ADMINAPP.CFG
  177.      file as 
  178.  
  179.         [BROADCASTS]
  180.         NetWareUserName = AdminApp
  181.         NetWarePassword = AdminAppPassword
  182.  
  183.  
  184.      ┌─────────────────┐
  185.      │ Loading the NLM │
  186.      └─────────────────┘
  187.  
  188.        At the file server console, enter
  189.  
  190.          LOAD ADMINAPP
  191.  
  192.      ┌────────────────────┐
  193.      │ Configuration File │
  194.      └────────────────────┘
  195.  
  196.        The configuration is read from the file SYS:SYSTEM/ADMINAPP.CFG.
  197.  
  198.        This file follows the Windows conventions of INI files, i.e. it
  199.        is divided into sections (indicated by section names in []),
  200.        which hold a number of assignments of the form
  201.  
  202.          Parameter = Value
  203.  
  204.        Blanks around the equals sign are ignored if present.
  205.        Comments can be entered on blank lines by prefixing them with a
  206.        semicolon. Upper/lowercase is ignored for the parameter names.
  207.  
  208.        Path values must be entered in NetWare format:
  209.  
  210.              Volume:Dir1\Dir2\Dir3
  211.  
  212.        The volume name must be specified. A forward slash may be used 
  213.        instead of a back slash. Volumes must be on the local server;
  214.        this NLM does not support logging in to other servers.
  215.  
  216.      ┌─────────────────────────────┐
  217.      │ Commands accepted by E-Mail │
  218.      └─────────────────────────────┘
  219.  
  220.      Administrator's Apprentice reads E-mail messages addressed to it
  221.      and processes the command specified on the "Subject:" line of the
  222.      message. The following commands are defined:
  223.  
  224.        PRINT Queuename
  225.  
  226.          Enters attached file(s) as job(s) in the specified print queue.
  227.  
  228.        STATUS [G][V][C][N][S][T][*]
  229.  
  230.          Returns a status report to the sender of the message.
  231.  
  232.          Contents: G = General, V = Volumes, C = Connections, N = NLMs,
  233.                    S = Screens, B = Bindery, P = Bindery + Properties
  234.  
  235.          Any or all of the optional report types may be specified. An 
  236.          Asterisk may be specified in place of the options to get all of
  237.          the reports. If no options are specified, a "Vols/Conns/Screens" 
  238.          report is returned.
  239.  
  240.        IGNORE
  241.  
  242.          Ignores this message completely.
  243.  
  244.        CONSOLE ConsolePassword
  245.  
  246.          Interprets the lines of the message body. The console password
  247.          must match the one specified in ADMINAPP.CFG for the message to
  248.          be processed.
  249.          The following keywords are recognized:
  250.  
  251.            COMMAND ConsoleCommandLine
  252.  
  253.              The console command line is passed to NetWare.
  254.  
  255.            STATUS MHS-Address;[G][V][C][S][T]
  256.  
  257.              Sends a status report to the address specified (in this case
  258.              it can be different from the sender's address).
  259.              The address must be present and is separated from the options
  260.              by a semicolon.
  261.  
  262.            DELAY NumberOfSeconds
  263.  
  264.              Delays for the specified number of seconds.
  265.              Note that polling for broadcast messages is not affected
  266.              because this continues to run in another thread.
  267.  
  268.          (CONSOLE sub-commands continued on next page)
  269.  
  270.          (continued: CONSOLE sub-commands)
  271.  
  272.            WAITFOR NLMLOAD NLMName [Timeout]
  273.            WAITFOR NLMUNLOAD NLMName [Timeout]
  274.  
  275.              Waits for the specified NLM to be loaded/unloaded.
  276.  
  277.              Note that the name is the internal name of the NLM, which
  278.              is not necessarily identical to the file name. If in doubt,
  279.              consult the information obtained with STATUS N.
  280.  
  281.              Note that only the base name is used for this command -
  282.              the file extension (.NLM, .LAN etc.) is ignored.
  283.  
  284.              If the NLM is not loaded/unloaded within the specified
  285.              timeout (in seconds), the command continues nonetheless.
  286.              The default timeout is 30 seconds.
  287.  
  288.              Example: WAITFOR NLMUNLOAD NGM 600
  289.  
  290.            CLOSE ScreenName
  291.  
  292.              Switches to the specified virtual screen and "presses the 
  293.              ENTER key" there. Used to close screens displaying the
  294.              message "Press any key to close screen".
  295.  
  296.            MESSAGE MHS-Address;Subject 
  297.  
  298.              Sends an MHS Message with the specified subject to the
  299.              specified address. Address and Subject are separated by a
  300.              semicolon.
  301.  
  302.            CRC FilePath
  303.  
  304.              Calculates the CRC32 (CCITT) of the specified file. This CRC
  305.              is the same as it is used by popular archiving programs such
  306.              as PKZIP or ARJ. Used to compare file versions with known
  307.              references. See also the description of the enclosed CRC32 
  308.              utility program for DOS.
  309.  
  310.            DIR FilePath [/S]
  311.  
  312.              Lists the directory. Note that you have to specify a file
  313.              wildcard, such as in
  314.  
  315.                DIR SYS:SYSTEM/*.*
  316.  
  317.              Option /S will cause subdirectories to be listed as well.
  318.              Note that the result is sent as the body of a message.
  319.              Therefore, if its length exceeds 64K and Global MHS has to
  320.              "downgrade" the message, i.e. convert from SMF-71 to SMF-70,
  321.              the message will be rejected by GMHS because GMHS insists
  322.              that an SMF-64 message cannot be longer than 64K.
  323.  
  324.              Such a limit does not exist if the format stays at SMF-71
  325.              or if the message is handled by MHS 1.5 or Connect².
  326.  
  327.            FETCH FilePath
  328.  
  329.              Attaches the specified file to a reply message.
  330.  
  331.          Example usage of the CONSOLE command to control the backup of a 
  332.          NetWare SQL database:
  333.  
  334.              To start backup, send the following message to AdminApp:
  335.  
  336.                Subject:  CONSOLE !You#will#never#guess!
  337.        
  338.                COMMAND Load NSUTIL -StartBU DatabaseName
  339.                DELAY   20
  340.                STATUS  Operator@Company;S
  341.                CLOSE   NSUTIL
  342.                MESSAGE Backup@Company;BACKUP MyServer
  343.  
  344.              This places the database in continuous-operation (backup)
  345.              mode, sends a status message to the administrator and closes
  346.              NSUTIL's screen. Then it sends a message to a backup gateway.
  347.  
  348.              This gateway (example shown next page) (ab)uses the MHS 
  349.              server to perform a backup procedure. Upon completion of 
  350.              that procedure, it sends the following message to AdminApp:
  351.  
  352.                Subject:  CONSOLE !You#will#never#guess!
  353.        
  354.                COMMAND Load NSUTIL -EndBU DatabaseName
  355.                DELAY   20
  356.                STATUS  Operator@Company;S
  357.                CLOSE   NSUTIL
  358.                MESSAGE Operator@Company;Database backup completed
  359.  
  360.  
  361.  
  362.              Example RUNIT.BAT for Infinite Technologies' Connect² MHS
  363.              compatible message router which can directly run batch files
  364.              as gateways:
  365.              (Note: Specify parameters for SENDIT on a single line!)
  366.  
  367.                @echo off
  368.                cls
  369.                echo.
  370.                echo.  RUNIT Gateway to control Backup
  371.                echo. 
  372.                echo.  Processing message from %gwfrom% ...
  373.                echo. 
  374.                rem   delete old log file, if present
  375.                if exist backup.log del result
  376.                rem   Parameter n is n-th Word on Subject line
  377.                rem   we're using Parameter 1 as a keyword
  378.                rem
  379.                rem   Command 1: BACKUP
  380.                rem
  381.                if not [%1]==[BACKUP] goto nobackup
  382.                BackupProgram Script=%2 Logfile=BACKUP.LOG
  383.                if errorlevel 1 goto backuperr
  384.                sendit /t%gwfrom% /f%GWNAME%@%GWNAME%(Backup)
  385.                      /sBackup completed. /b /q
  386.                goto cont1
  387.                :backuperr
  388.                sendit /t%Operator@Company /f%GWNAME%@%GWNAME%(Backup)
  389.                      /sBackup FAILED! /bBACKUP.LOG /q
  390.                :cont
  391.                sendit /tAdminapp@Company /f%GWNAME%@%GWNAME%(Backup)
  392.                      /sCONSOLE !You#will#never#guess! /bENDBU.MSG
  393.                sendit /t%Operator@Company /f%GWNAME%@%GWNAME%(Backup)
  394.                      /sBackup completed. /bBACKUP.LOG /q
  395.                goto cont2
  396.                rem
  397.                rem   Example command 2:
  398.                rem
  399.                if not [%1]==[LIST] goto cont2
  400.                BackupProgram List=%2 Logfile=BACKUP.LOG
  401.                sendit /t%Operator@Company /f%GWNAME%@%GWNAME%(Backup)
  402.                      /sRequested List /bBACKUP.LOG /q
  403.                :cont2
  404.                rem   More commands can be implemented the same way
  405.                rem
  406.                rem   Delete already-processed message (C² doesn't)
  407.                del %GWDIR%OUT\%GWMSG%
  408.                echo - Done!
  409.  
  410.              (STARTBU.MSG/ENDBU.MSG contain the text of the previously
  411.              shown mail messages).
  412.  
  413.              Please refer to the documentation of Connect² as well.
  414.  
  415.              For sites running Global MHS or MHS 1.5, Infinite
  416.              Technologies offers a gateway called RunIt! that offers
  417.              this functionality for these environments.
  418.  
  419.      ┌───────────────────────────┐
  420.      │ The CRC32 Utility Program │
  421.      └───────────────────────────┘
  422.  
  423.      The CRC32 program is a DOS-based utility to calculate the 32bit CRC 
  424.      (cyclic redundancy check) checksum as defined by ANSI X3.66, 
  425.      FIPS PUB 71, FED-STD-1003 or CCITT/ITU-T X.25.
  426.  
  427.      This is the same CRC method as implemented in popular compression or 
  428.      archiving programs such as PKZIP(tm), ARJ(tm) and others.
  429.  
  430.      Note to those who want to know it all: The polynomial being used is
  431.      X^32+X^26+X^23+X^22+X^16+X^12+X^11+X^10+X^8+X^7+X^5+X^4+X^2+X^1+X^0.
  432.  
  433.      Using the program
  434.      ─────────────────
  435.  
  436.        crc32 filespec { filespec }
  437.  
  438.      Filespecs may use the wildcard characters * and ? as common in DOS.
  439.  
  440.      The option /X<ext>{,<ext>} excludes files with extension <ext> for
  441.      the rest of the command line or up to the next /X option.
  442.  
  443.      Progress of the CRC calculation is indicated by a spinning line.
  444.      The program's output may still be redirected by DOS.
  445.  
  446.  
  447.      Example
  448.      ───────
  449.  
  450.        crc32 /XSYS SYS:SYSTEM/*.* /X SYS:PUBLIC/*.*
  451.  
  452.      Hints
  453.      ─────
  454.  
  455.      The same file may be specified multiple times on the command 
  456.      line to test disk/LAN integrity, e.g. 
  457.  
  458.        crc32 test.dat test.dat test.dat test.dat test.dat test.dat 
  459.  
  460.      The program should of course calculate the same CRC value 
  461.      every time.
  462.  
  463.      To quickly tell if two files are equal, use (for example)
  464.  
  465.        crc32 SYS:SYSTEM/CLIB.NLM SYS:SYSTEM/CLIB.OLD
  466.  
  467.      The advantage to comparing files with a program like DIFF or FC 
  468.      is that using ADMINAPP, the CRC32 value can be computed and sent 
  469.      quickly for a remote file, even if it is several megabytes in 
  470.      size. FC would require the whole file to be transferred for the 
  471.      comparison.
  472.  
  473.      Alternatively, the CRC can bee transferred by even lower-tech
  474.      methods, such as reading over the phone.
  475.  
  476.      ┌────────────────────────────────────────────────────────┐
  477.      │ Planned enhancements to AdminApp for upcoming releases │
  478.      └────────────────────────────────────────────────────────┘
  479.  
  480.      - Monitoring NetWare internal events such as Volume mount/dismount,
  481.        user login/logout, bindery security change etc., configurable 
  482.        through the INI file and/or E-mail commands
  483.  
  484.      - Monitoring log files for error messages
  485.  
  486.      - Conditional execution & labels in CONSOLE subcommand-blocks,
  487.        e.g. depending on the result of WAITFOR NLMLOAD
  488.  
  489.      - Exploit the diagnostics capabilities built into NetWare 4 to return
  490.        information about memory utilization etc.
  491.  
  492.  
  493.      Any other suggestions are cordially welcomed!
  494.  
  495.  
  496.      ┌──────────────────┐
  497.      │ Revision History │
  498.      └──────────────────┘
  499.  
  500.        V1.00   94/10/23  Initial Beta Release.
  501.        V1.00A  94/10/30  Added NLM Info, WAITFOR NLMLOAD, 
  502.                          WAITFOR NLMLOAD commands.
  503.        V1.10   94/11/07  Added NetWare 3.x support for NLM Info/WAIT 
  504.                          commands. Cleaned up UNLOAD code. Beta Rel. 2.
  505.        V1.20   94/12/27  Release candidate
  506.        V1.20A  94/12/30  Fixed NW 3.11 NLM list garbage. 
  507.                          First production release.
  508.        V1.20B  95/01/11  Moved ConsolePassword= setting to [Settings]
  509.                          section. Added MailPollDelay= setting.
  510.                          Clarified documentation.
  511.  
  512.      ┌──────────────────────┐
  513.      │ Ordering Information │
  514.      └──────────────────────┘
  515.  
  516.      Administrator's Apprentice is supplied as a 30-day evaluation
  517.      version. You are welcome to try out the program during that period.
  518.      After this period, the evaluation version will cease to run.
  519.      You may install a purchased license at any time without any change
  520.      in configuration. 
  521.  
  522.      You are also welcome to give copies of this evaluation package to
  523.      whomever you wish, provided that you pass the original archive in
  524.      its entirety.
  525.  
  526.      The price of the licensed version is US $280 per server in the U.S.,
  527.      or ATS 3000 in Europe and elsewhere, including E-mail delivery, but 
  528.      excluding mail or courier S/H.
  529.  
  530.      E-mail if you want to negotiate site or corporate licenses.
  531.      Resellers please inquire about terms.
  532.  
  533.      To order the licensed version, contact
  534.  
  535.          Peter Holzleitner Consulting
  536.          A-3704 Grosswetzdorf 1
  537.          Austria, Europe
  538.  
  539.      by E-mail as
  540.  
  541.        MHS: 
  542.              Peter@PHConslt  (via LEND-ING, CSERVE, NHUB)
  543.  
  544.        Internet:
  545.  
  546.              pholzl@ping.at
  547.  
  548.        From CompuServe, you may enter 
  549.  
  550.              MHS:Peter@PHCONSLT       (preferred as it is faster for me)
  551.          or
  552.              100427,234
  553.  
  554.